package com.seedog.mq;

import com.seedog.mq.model.Message;
import com.seedog.mq.exception.TopicNotFoundException;
import com.seedog.mq.exception.ConsumerException;

/**
 * 消息消费者接口，用于从消息队列接收消息
 */
public interface Consumer {
    /**
     * 获取消费者ID
     * @return 消费者ID
     */
    String getConsumerId();
    
    /**
     * 订阅指定主题
     * @param topicName 主题名称
     * @throws TopicNotFoundException 如果主题不存在
     */
    void subscribe(String topicName) throws TopicNotFoundException;
    
    /**
     * 取消订阅指定主题
     * @param topicName 主题名称
     * @return 是否取消成功
     */
    boolean unsubscribe(String topicName);
    
    /**
     * 从订阅的主题中获取消息，不阻塞
     * @param topicName 主题名称
     * @return 消息对象，如果没有消息则返回null
     * @throws TopicNotFoundException 如果主题不存在
     * @throws ConsumerException 如果接收消息失败
     */
    Message poll(String topicName) throws TopicNotFoundException, ConsumerException;
    
    /**
     * 从订阅的主题中获取消息，可设置超时时间
     * @param topicName 主题名称
     * @param timeout 超时时间（毫秒）
     * @return 消息对象，如果超时则返回null
     * @throws TopicNotFoundException 如果主题不存在
     * @throws ConsumerException 如果接收消息失败
     */
    Message poll(String topicName, long timeout) throws TopicNotFoundException, ConsumerException;
    
    /**
     * 确认消息已被消费
     * @param topicName 主题名称
     * @param messageId 消息ID
     * @return 是否确认成功
     * @throws TopicNotFoundException 如果主题不存在
     * @throws ConsumerException 如果确认失败
     */
    boolean acknowledge(String topicName, String messageId) throws TopicNotFoundException, ConsumerException;
    
    /**
     * 关闭消费者
     */
    void close();
}